Related #3702. Related #3621. Related #3620.

Fixes #2770.

Changelog Entry

Added

• Resolves #2770. Added customer satisfactory (CSAT) card, by @compulim, in PR #4899

Customer Satisfactory Card (CSAT card)

This is related to PR #4899.

Description

Power Virtual Agents and many customers implemented customer satisfactory (CSAT) cards using Adaptive Cards. However, as Adaptive Cards is designed for general purpose. Thus, the accessibility experience is not great for CSAT cards.

We are adding new attachment renderer for CSAT cards by leveraging https://schema.org/ReviewAction.

Design

We are using https://schema.org/ReviewAction for the representation of the CSAT card. The following is excerpt of the activity containing the CSAT card.

{
   "type": "message",
   "attachments": [
      {
         "content": {
            "@context": "https://schema.org",
            "@type": "ReviewAction",
            "actionStatus": "PotentialActionStatus",
            "description": "Great! Please rate your experience.",
            "resultReview": {
               "@type": "Review",
               "reviewRating": {
                  "@type": "Rating",
                  "ratingValue-input": {
                     "@type": "PropertyValueSpecification",
                     "valueName": "rate"
                  }
               }
            },
            "target": {
               "@type": "EntryPoint",
               "actionPlatform": "https://directline.botframework.com",
               "urlTemplate": "ms-directline-postback:?value={rate}"
            }
         },
         "contentType": "application/ld+json"
      }
   ]
}

Explanation of fields

Current designs and limitations:

• Subclasses are not supported. resultReview must be thing of "Review". "UserReview" and other subclass of "Review" is not supported
• Rating must be 1 to 5 stars. resultReview.reviewRating.bestRating and resultReview.reviewRating.worstRating are ignored
• If actionStatus is CompletedActionStatus, it indicates the review is submitted, thus, target is optional. Otherwise, review should be submittable and target must be specified
• Despite target could be a non-templated URL, it is highly recommended target is a thing of EntryPoint

Target URL

Currently, only ratingValue-input is supported. In the future, all fields in the Thing will be supported.

When the user change the rating, it will change the resultReview.reviewRating.ratingValue. In Schema.org actions, the ratingValue-input will be used to describe how the ratingValue is used in the request body of the action.

In the example payload, ratingValue-input.valueName is rate. When filling the target.urlTemplate, it will replace the variable rate with the user rating.

If the user rated 4, the URL template will be expanded as by replacing variable rate with 4:

- ms-directline-postback:?value={rate}
+ ms-directline-postback:?value=4

Thus, the postback activity payload will become:

{
   "channelData": {
      "postBack": true
   },
   "text": "4",
   "type": "message"
}

Note: when using postback for a string value, it will send via text field.

Followings are supported protocol and their query parameters:

http:/https: are not supported at the moment.

For details of parameters, please refer to Direct Line Activity spec.

Specific Changes

• Added Customer Satisfactory attachment and its middleware
• Added useOpenURL for internal use on ms-directline-*: protocol
• Fixed bugs in RovingTabIndexProvider
  • END should set the focus on the last element in the list
• OrgSchemaThing should not typed out type: type is strictly for entities only
• Added docs/CUSTOMER_SATISFACTORY_CARD.md

• I have added tests and executed them locally
• I have updated CHANGELOG.md
• I have updated documentation

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)